> ## Documentation Index
> Fetch the complete documentation index at: https://www.sikaru.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Experience, Harbor Trajectories, and OpenInference

> Record Sikaru Experience trajectories, upload Harbor ATIF agent trajectories, and ingest OpenInference-compatible trace data for continual learning and eval evidence.

`Experience` is Sikaru's agent trajectory abstraction. It captures the episode-level data that continual learning and agent eval systems need: messages, tool calls, tool results, telemetry events, outcomes, corrections, failures, and rewards.

Sikaru Experience is compatible with the broader agent trajectory ecosystem:

* Harbor ATIF trajectories can be uploaded to Sikaru.
* Sikaru trajectories can export to Harbor ATIF v1.7.
* OpenInference spans can be uploaded directly.
* OTLP resource spans can be normalized into the same trace stream.
* Native Sikaru Experience payloads, Harbor ATIF, and OpenInference-compatible traces all feed the same issue mining, eval seed, and improvement evidence loop.

`Experience` and `traces` write to `POST /v1/trace-streams`.

## Why Experience matters

Managed agents improve when Sikaru can connect what happened to whether it was good. A single Experience can carry:

| Signal                   | Why it matters                                                                    |
| ------------------------ | --------------------------------------------------------------------------------- |
| Messages                 | The user request and assistant behavior.                                          |
| Tool calls and results   | The product capabilities the agent used and what came back.                       |
| Feedback and corrections | Human-provided guidance about the better behavior.                                |
| Failures                 | Known misses, exceptions, timeouts, rejected answers, or policy issues.           |
| Outcomes and rewards     | Task success, acceptance, escalation quality, or other product-defined measures.  |
| Metadata                 | Project, account, user, conversation, environment, source, and trace identifiers. |

This is the evidence Sikaru uses to find repeated failures, select or create eval cases, and propose reviewed behavior updates.

## Record a product-run experience

Use `Experience` when your product already executed the agent behavior itself.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    experience = sikaru.experience(
        "support",
        user="user_123",
        conversation="conv_123",
        session="session_123",
    )

    experience.user("Find renewal risk.")
    call = experience.tool_call("crm.search", {"account_id": "acct_123"})
    experience.tool_result(call, {"risk": "legal review"})
    experience.assistant("Renewal risk is legal review.")
    experience.signal("approval.completed", {"approved": True})
    experience.outcome("operator_acceptance", 1.0, feedback="accepted")

    result = experience.commit(dataset="live")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```ts theme={null}
    const experience = sikaru.experience("support", {
      userId: "user_123",
      conversationId: "conv_123",
      sessionId: "session_123",
    });

    experience.user("Find renewal risk.");
    const call = experience.toolCall("crm.search", { account_id: "acct_123" });
    experience.toolResult(call, { risk: "legal review" });
    experience.assistant("Renewal risk is legal review.");
    experience.signal("approval.completed", { approved: true });
    experience.outcome("operator_acceptance", 1, { feedback: "accepted" });

    const result = await experience.commit({ dataset: "live" });
    ```
  </Tab>
</Tabs>

## Add corrections and failures

Corrections and failures make the continual learning loop actionable. Use corrections when a user, operator, evaluator, or policy reviewer identifies the better behavior. Use failures when a run produced a known miss, exception, policy issue, timeout, or rejected answer.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    experience.correction("Use legal-review wording before recommending renewal terms.")
    experience.failure("retry_needed", message="first answer was vague")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```ts theme={null}
    experience.correction("Use legal-review wording before recommending renewal terms.");
    experience.failure("retry_needed", { message: "first answer was vague" });
    ```
  </Tab>
</Tabs>

## Build a Sikaru trajectory from existing messages

Use this path when another agent framework already produced messages and tool calls.

```python theme={null}
from sikaru_sdk import build_trajectory_from_messages, messages_from_openai_chat

trajectory = build_trajectory_from_messages(
    messages_from_openai_chat(messages),
    conversation_id="conv_123",
    trace_id="trace_123",
    data_source="openai-agent",
)

sikaru.traces.upload_trajectory(trajectory, dataset="prod")
```

## Upload OpenInference-compatible traces

OpenInference spans are useful for migrations, low-level instrumentation, and existing tracing pipelines.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    sikaru.traces.upload(openinference_spans, dataset="prod")
    sikaru.traces.upload_file("./openinference-export.jsonl", dataset="prod")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```ts theme={null}
    await sikaru.traces.upload(openinferenceSpans, {
      dataset: "prod",
    });
    ```
  </Tab>
</Tabs>

Use deterministic idempotency keys for retried single-batch uploads.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    sikaru.traces.upload(
        openinference_spans,
        dataset="prod",
        idempotency_key="trace-batch-2026-06-14-001",
    )
    ```
  </Tab>

  <Tab title="TypeScript">
    ```ts theme={null}
    await sikaru.traces.upload(openinferenceSpans, {
      dataset: "prod",
      idempotencyKey: "trace-batch-2026-06-14-001",
    });
    ```
  </Tab>
</Tabs>

## Upload OTLP and Harbor ATIF

The Python SDK has helpers for direct OpenTelemetry OTLP resource spans and Harbor ATIF trajectories.

```python theme={null}
sikaru.traces.upload_otlp_resource_spans(
    otlp_payload["resourceSpans"],
    dataset="prod",
    metadata={"source": "otel-exporter", "account_id": "acme"},
)

sikaru.traces.upload_harbor_trajectory(
    atif_trajectory,
    dataset="harbor-evals",
    metadata={"source": "harbor", "account_id": "acme"},
)
```

Export a Sikaru trajectory to Harbor ATIF v1.7 when you want to run or share agent trajectory evals outside Sikaru.

```python theme={null}
atif = trajectory.to_harbor_atif(
    agent_name="support",
    agent_version="2026.7.3",
)
```

## Metadata for evals and mining

Attach stable metadata that helps Sikaru group, search, and explain issues.

| Metadata          | Typical value                                         |
| ----------------- | ----------------------------------------------------- |
| `project_id`      | Added by the SDK from the configured project.         |
| `account_id`      | Customer, tenant, or workspace account.               |
| `environment`     | `production`, `staging`, or another deployment label. |
| `source`          | Agent framework, service, or SDK source name.         |
| `user_id`         | Product user ID.                                      |
| `conversation_id` | Conversation, ticket, thread, or workflow ID.         |

<Info>
  Treat outcomes, corrections, and failures as product facts. Sikaru uses them as evidence for issue mining, eval seed selection, regression checks, and reviewed improvements.
</Info>