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

> ## Agent Instructions
> These docs describe the Ancha CLI, npm package @ancha-labs/cli, and the hosted workspace at app.ancha.io. Coding agents should start at https://docs.ancha.io/coding-agents. Run the CLI as `ancha` after `npm install -g @ancha-labs/cli`, or as `npx -y @ancha-labs/cli` without installing. Pass --json for machine-readable output, or set ANCHA_JSON=1. Every command ends with a `next:` line naming the next command. Exit codes: 0 pass, 1 a check failed or a comparison regressed, 2 usage, config or authentication error, 3 infrastructure error, 4 unimplemented endpoint with --strict.

# Trace IR

> Ancha Trace IR v1: one agent episode as JSON Lines, a header then one record per API call, webhook, tool call or model call. Ancha stores traces in it, imports it, and exports runs as it.

Ancha Trace IR is the one format Ancha keeps traces in. OTLP traces are converted to it, `ancha import` accepts it, `ancha runs export` writes it, and **Download what Ancha stored** gives it back.

A file is [JSON Lines](https://jsonlines.org): a header on the first line, then one record per line in time order. One file can hold one trace.

## Header

```json theme={null}
{"ir":"ancha.trace/v1","trace_id":"85ff075cdaec081c188c079b0eab6abd","agent":"acme-oncall","source":"otlp","started_at":"2026-10-21T13:59:59.972Z"}
```

| Field | Meaning |
| - | - |
| `ir` | Always `ancha.trace/v1`. Required. |
| `trace_id` | The trace's id in your tracing tool, or any id you choose. |
| `agent` | Your agent's name, from the OpenTelemetry `service.name`. |
| `source` | Where it came from: `otlp`, `file` or `ancha-run`. |
| `started_at` | The time of the first record. |

## Records

Every record has `kind` and `t`, an ISO 8601 time. Most have `id`, the span id.

### `call`: an API call your agent made

```json theme={null}
{"kind":"call","id":"5278c6c117431b84","t":"2026-10-21T14:00:12.104Z","service":"datadog","method":"GET","url":"https://api.datadoghq.com/api/v1/monitor/343937855","request":{},"response":{"status":200,"body":{"id":343937855,"name":"Orders request failures","overall_state":"Alert"}}}
```

| Field | Meaning |
| - | - |
| `service` | The tool, such as `slack` or `stripe`. Optional: Ancha derives it from the URL's host. |
| `method`, `url` | The request line, with the vendor's real host and the query string. |
| `request.body` | The request body, parsed: JSON, or form fields as an object. |
| `response.status`, `response.body` | The answer. Ancha rebuilds the world from these bodies. |
| `t_end` | When the answer arrived. Optional. |

### `inbound`: a webhook your agent received

```json theme={null}
{"kind":"inbound","id":"9c1d2e3f4a5b6c7d","t":"2026-10-21T14:00:00.002Z","service":"datadog","payload":{"alert_id":"343937855","alert_transition":"Triggered"}}
```

### `llm`: a model call

```json theme={null}
{"kind":"llm","id":"ae03e898d8bb2fba","t":"2026-10-21T14:00:00.002Z","model":"anthropic/claude-haiku-5.5","usage":{"input":4373,"output":131},"input":[{"role":"user","text":"Orders requests are failing after a deploy. …"}]}
```

`input` holds the user and assistant messages the call was sent, in order. System instructions are never kept. The first user message of the first model call is what Ancha takes as your agent's task.

### `tool`: a tool your agent called

```json theme={null}
{"kind":"tool","id":"0a1b2c3d4e5f6a7b","t":"2026-10-21T14:00:03.411Z","name":"slack_history","args":{"channel":"C48SKYPN1S3"},"result":{"messages":[]}}
```

### `outcome`: how the episode ended

```json theme={null}
{"kind":"outcome","t":"2026-10-21T14:01:12.083Z","status":"error","detail":"the customer reported the reply went to the channel"}
```

## Rules

* Write records in time order.
* A file whose first line is not an `ancha.trace/v1` header, or with a record of another `kind` or without a valid `t`, is refused with the line at fault.
* Credentials, emails and phone numbers are removed or replaced before a trace is stored. See [Trace privacy](https://docs.ancha.io/cloud/trace-privacy.md).

## Produce it

| From | How |
| - | - |
| OpenTelemetry | Send spans to your workspace. See [OTLP](https://docs.ancha.io/reference/otlp.md). |
| An `ancha run` | `ancha runs export <run>` writes each attempt as one file. See [ancha runs](https://docs.ancha.io/cli/runs.md). |
| Anything else | Write the header and records yourself, then `ancha import <file>`. |


## Related topics

- [Traces](https://docs.ancha.io/cloud/traces.md)
- [From a production trace to a failing test](https://docs.ancha.io/guides/rebuild-from-traces.md)
- [ancha runs](https://docs.ancha.io/cli/runs.md)
- [OTLP](https://docs.ancha.io/reference/otlp.md)
- [ancha import](https://docs.ancha.io/cli/import.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.