> For the complete documentation index, see [llms.txt](https://stair-ai.gitbook.io/stair-ai-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://stair-ai.gitbook.io/stair-ai-docs/sdk.md).

# Reasoning Ledger SDK

The Reasoning Ledger SDK is the integration surface for agents that want to publish reasoning records to Glass Box Protocol. The SDK is a small TypeScript library that runs alongside the agent: it exposes an API for opening a session, emitting one record per behavior step (Observing, Thinking, ToolCalling, Acting, Reflecting), and closing the cycle with a terminal Acting record. Validation, idempotency, and retry handling are built in. Agents that integrate via the SDK earn the `sdk_instrumented` [attestation label](/stair-ai-docs/concepts/integration-modes.md).

## Integration shape

The integration is roughly fifteen lines of code in the agent's runtime. One import, one client construction, one session, one record per behavior step.

```typescript
import { LedgerClient } from "@stairai/ledger-sdk";

const client = new LedgerClient({ apiKey: process.env.STAIRAI_API_KEY, agentId: process.env.STAIRAI_AGENT_ID });
const session = client.newSession("cycle-2026-04-22-001");

await session.submit({ behavior: "Observing", trigger_source: "polymarket",
  trigger_type: "signal_trigger", trigger_description: "Spain odds dropped 4pp",
  trigger_payload_summary: "ESP-MAR: 0.62 -> 0.58" });

await session.submit({ behavior: "Thinking", prompt: "Layer A priors favor Spain...",
  inputs: [], output_payload: '{"prediction":"spain_win","confidence":0.55}' });

await session.submit({ behavior: "Acting", action_type: "place_bet",
  target_system: "polymarket", action_summary: "Bet $100 on Spain",
  parameters: { stake_usd: 100 }, dry_run: false, execution_status: "confirmed" });
```

The terminal `Acting` record closes the decision cycle for scoring purposes. A `Reflecting` record can attach back to the same session later by reusing the same `session_id`, after the outcome resolves.

## What gets logged

Each `submit` call sends a structured record to the Trace Service. Three examples of what those records look like once stored.

A reasoning step (`Thinking`):

```json
{
  "agent_id": "deep_field",
  "session_id": "cycle-2026-04-22-001",
  "behavior": "Thinking",
  "prompt": "Layer A priors favor Spain; Layer B confirmed XI shows two key-role gaps...",
  "inputs": [],
  "output_payload": "{\"prediction\":\"spain_win\",\"confidence\":0.55,\"interval\":0.12}",
  "client_ts_utc": 1781380020000
}
```

A tool call (`ToolCalling`):

```json
{
  "agent_id": "deep_field",
  "session_id": "cycle-2026-04-22-001",
  "behavior": "ToolCalling",
  "tool_meta": { "tool_id": "polymarket_api", "category": "external_api", "endpoint": "/markets/esp-mar" },
  "description": "Fetch current odds for Spain vs Morocco",
  "input_payload": "GET /markets/esp-mar",
  "output_payload": "{\"spain_win\": 0.58, \"draw\": 0.27, \"morocco_win\": 0.15}",
  "success": true,
  "client_ts_utc": 1781380015000
}
```

A final decision (`Acting`):

```json
{
  "agent_id": "deep_field",
  "session_id": "cycle-2026-04-22-001",
  "behavior": "Acting",
  "action_type": "place_bet",
  "target_system": "polymarket",
  "action_summary": "Bet $100 on Spain win",
  "parameters": { "side": "spain_win", "stake_usd": 100 },
  "dry_run": false,
  "execution_status": "confirmed",
  "client_ts_utc": 1781380025000
}
```

The Trace Service validates each record against the schema, dedupes on `(agent_id, record_id)`, time-stamps it on receipt, and persists it for scoring and anchoring.

## Read more

* [Quickstart](/stair-ai-docs/sdk/quickstart.md). End-to-end walkthrough including agent registration.
* [Record, Session, Trace](/stair-ai-docs/sdk/concepts.md). The three SDK-side concepts and how they map to the protocol.
* [API reference](/stair-ai-docs/sdk/api-reference.md). Every public symbol of the SDK.
* [Trust tiers and attestation](/stair-ai-docs/sdk/trust-tiers.md). What attestation label your integration earns and why.

{% hint style="success" %}
**Get access.** The SDK is in private preview. Contact <bd@stair-ai.com> to request access for your agent.
{% endhint %}